Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 2 - Control Manager Reference / Control Manager Functions

Creating and Removing Controls /

NewControl

CHANGED WITH THE APPEARANCE MANAGER

Creates a control based on information passed in its parameters that describes the control.

pascal ControlHandle NewControl (
                     WindowPtr owningWindow,
                     const Rect *boundsRect,
                     ConstStr255Param controlTitle,
                     Boolean initiallyVisible,
                     SInt16 initialValue,
                     SInt16 minimumValue,
                     SInt16 maximumValue,
                     SInt16 procID,
                     SInt32 controlReference);

owningWindow

On input, a pointer to the window in which you want to place the control. All coordinates pertaining to the control are interpreted in this window's local coordinate system.

boundsRect

On input, a pointer to a rectangle, specified in the given window's local coordinates, that encloses the control and thus determines its size and location. When specifying this rectangle, you should follow the guidelines presented in "Dialog Box Layout", in Mac OS 8 Human Interface Guidelines, for control placement and alignment.

controlTitle

The title string, used for push buttons, checkboxes, radio buttons, and pop-up menus. When specifying a multiple-line title, separate the lines with the ASCII character code 0x0D (carriage return). For controls that don't use titles, pass an empty string.

initiallyVisible

A Boolean value specifying the visible/invisible state for the control. If you pass true in this parameter, NewControl draws the control immediately, without using your window's standard updating mechanism. If you pass false, you must later use ShowControl to display the control.

initialValue

The initial setting for the control; see "Settings Values for Standard Controls".

minimumValue

The minimum setting for the control; see "Settings Values for Standard Controls".

maximumValue

The maximum setting for the control; see "Settings Values for Standard Controls".

procID

The control definition ID; see Table 2-1. If the control definition function isn't in memory, it is read in.

controlReference

The control's reference value, which is set and used only by your application.

function result

Returns a handle to the control described in its parameters. If NewControl runs out of memory or fails, it returns nil.

DISCUSSION

The NewControl function creates a control structure from the information you specify in its parameters, adds the control structure to the control list for the specified window, and returns as its function result a handle to the control. You can use this handle when referring to the control in most other Control Manager functions. Generally, you should use the function GetNewControl instead of NewControl, because GetNewControl is a resource-based control-creation function that allows you to localize your application without recompiling.

When an embedding hierarchy is established within a window, NewControl automatically embeds the newly created control in the root control of the owning window. See "Embedding Controls".

If you are using standard system controls, default colors are used and the control color table resource is ignored. To use colors other than the default colors, write your own custom control definition function.

SEE ALSO

GetNewControl.

WHEN THE APPEARANCE MANAGER IS NOT AVAILABLE

NewControl does not embed the newly created control in the root control of the owning window because embedding hierarchies are not supported.